[Docs] v3-->v4 migration guide - #2613
Merged
Merged
Conversation
|
Kylejeong2
reviewed
Aug 6, 2026
akeimach
force-pushed
the
alyssamaruyama/stg-2685-do-a-migration-guide
branch
from
August 7, 2026 06:14
29e0822 to
8279a88
Compare
akeimach
marked this pull request as ready for review
August 7, 2026 14:16
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
All reported issues were addressed across 2 files
Architecture diagram
sequenceDiagram
participant Dev as Developer
participant AS as AI Assistant
participant Rules as AI Rules File
participant SH as Stagehand v4 SDK
participant Browser as Browser Instance
participant Page as Page / Context
participant Model as LLM Model
Note over Dev,Model: v3→v4 Migration - Code Mode Path
Dev->>AS: Request: "Write a Stagehand v4 script that..."
AS->>Rules: Read AI rules (v4 API conventions)
Rules-->>AS: Return rules
AS->>SH: Generate script using Stagehand.create()
AS-->>Dev: Return generated script
Dev->>SH: Execute generated script
SH->>Browser: browserbase.launch() / localBrowser.launch()
Browser-->>SH: Return browser instance
SH->>SH: Stagehand.create({ browser })
SH->>Browser: browser.context.newPage(url)
Browser-->>SH: Return page
alt Deterministic operations (stable selectors)
SH->>Page: page.locator().click()
SH->>Page: page.goto()
Page-->>SH: Standard Playwright responses
else Model-backed operations (natural language)
SH->>Page: page.snapshot()
Page-->>SH: formattedTree + xpathMap
SH->>Model: stagehand.act("Open most-commented story")
Model-->>SH: Action instruction
SH->>Page: Locator-based action
SH->>Model: stagehand.extract("Extract top 5 comments", schema)
Model-->>SH: Structured data
end
SH-->>Dev: Return { data, metadata }
Dev->>SH: stagehand.close()
SH->>Browser: browser.close()
Note over Dev,Model: v3→v4 Migration - Tool Calling Path
Dev->>AS: Request: "Create tool-calling loop"
AS->>Rules: Read AI rules
Rules-->>AS: Return rules
AS-->>Dev: Return tool definitions
alt Tool execution loop
loop Each step
Dev->>Model: Call with tool definitions + context
Model-->>Dev: Select tool + parameters
alt Navigation tools
Dev->>Page: page.goto() / page.reload() / page.goBack()
else Perception tools
Dev->>Page: page.snapshot() / page.screenshot()
Page-->>Dev: formattedTree (for next model call)
else Element interaction
Dev->>Page: locator.click() / locator.fill()
else Model-backed tools
Dev->>SH: stagehand.act() / stagehand.extract()
SH->>Model: Process natural language instruction
Model-->>SH: Result
SH-->>Dev: { data, metadata }
end
end
end
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
akeimach
force-pushed
the
alyssamaruyama/stg-2685-do-a-migration-guide
branch
from
August 7, 2026 15:16
0595ba6 to
3db26a8
Compare
Contributor
There was a problem hiding this comment.
All reported issues were addressed across 2 files
Architecture diagram
sequenceDiagram
participant CodeGen as AI Coding Assistant
participant UserScript as Stagehand Script
participant SDK as Stagehand v4 SDK
participant Page as Browser Page
participant Model as AI Model (LLM)
participant Snap as Page Snapshot
Note over CodeGen,Snap: Migration Path 1: Code Mode (Recommended)
UserScript->>SDK: browserbase.launch() / localBrowser.launch()
SDK-->>UserScript: Browser instance
UserScript->>SDK: Stagehand.create({ browser })
SDK-->>UserScript: Stagehand instance
UserScript->>Page: browser.context.newPage(url)
Page-->>UserScript: Page handle
alt Deterministic Navigation
UserScript->>Page: page.locator(selector).click()
UserScript->>Page: page.goto(url)
Page-->>UserScript: DOM state
else Model-backed Interaction
UserScript->>SDK: stagehand.act("Natural language instruction")
SDK->>Model: Process instruction
Model-->>SDK: Action plan
SDK->>Page: Execute action
Page-->>SDK: Result
SDK-->>UserScript: { data, metadata }
end
UserScript->>SDK: stagehand.extract("Extract structured data", schema)
SDK->>Page: Read page content
Page-->>SDK: Raw content
SDK->>Model: Parse structure
Model-->>SDK: Structured result
SDK-->>UserScript: { data, metadata }
Note over CodeGen,Snap: Migration Path 2: Tool-Calling Loop
UserScript->>Page: page.snapshot()
Page->>Snap: Build formattedTree + xpathMap
Snap-->>UserScript: Accessibility tree + selectors
loop Each step
UserScript->>Model: Expose tools (click, fill, snapshot, act, extract, etc.)
Model->>SDK: Choose tool + parameters
alt Deterministic tool
SDK->>Page: Use Playwright locator (click, fill, goto)
Page-->>SDK: Result
else Model-backed tool
SDK->>Model: Process natural language
Model-->>SDK: Structured action
SDK->>Page: Execute
Page-->>SDK: Result
end
SDK-->>UserScript: { data, metadata }
end
Note over UserScript,SDK: Cleanup
UserScript->>SDK: stagehand.close()
UserScript->>SDK: browser.close()
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
Kylejeong2
reviewed
Aug 7, 2026
Kylejeong2
approved these changes
Aug 8, 2026
Contributor
There was a problem hiding this comment.
All reported issues were addressed across 1 file (changes from recent commits).
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
why
what changed
test plan
Summary by cubic
Adds a v3→v4 migration guide with two paths to replace
agent()—code mode or a tool-calling loop—plus a quick reference, troubleshooting, and whyagent()was removed. Updates the docs nav with a new “Migration guide” group and aligns with Linear STG-2685. Includes TypeScript, Python, and Go examples.v4/migrations/v3with TypeScript, Python, and Go examples using@browserbasehq/stagehand; includes AI rules setup, a copy/paste migration prompt, a recommended order, quick reference, troubleshooting, and a TODO for an integrations overview link.agent()with either: (1) Code mode (generate a v4 script), or (2) a tool-calling loop exposing the full API with a suggested tool surface; usepage.snapshot()for planner context; optional page tools via WebMCP.browserbase.launch()/localBrowser.launch()andStagehand.create({ browser })(constructor is private).browser.contextwith async getters;act(),extract(), andobserve()moved to the Stagehand instance (target tabs with{ page }); prefer retryingobserve().{ data, metadata };extract()uses positional args.model: { modelName, apiKey }; enable server caching withcache(requires a Browserbase browser).logging: { level, format, onLog }; metrics viaawait stagehand.metrics().page.deepLocator()removed (usepage.locator()with the same selectors).Written for commit 698c8be. Summary will update on new commits.